
=======================================
EDGE-Classic Pack Structure and Usage
=======================================

by The EDGE Team.  December 2023.

=======================================
Introduction
=======================================

The term "Pack" is used to refer to both compressed archives and whole directories that are passed
to the program via the -file and -dir parameters, drag-and-drop, response files, et cetera. They are
handled in the same manner by the underlying program, and as such follow the same file hierarchy and
usage patterns.

=======================================
Supported Archive Formats
=======================================

Zip-compressed archives with the following extensions are recognized and loaded by the program:

.epk - An abbreviation of "EDGE PacKage"; this is the preferred extension to differentiate EDGE-specific
       archives from archives supported by other source ports. Currently works with SLADE; other editing
       tools may not recognize this by default (yet).

.pk3 - The most common extension recognized by various editing tools, but runs a high risk of being mistaken for a 
       file meant to be used with the ZDoom family of ports.

.zip - The default format for files from the /idgames archive, this should also be easily loaded by most editing tools.

=======================================
Supported Filenames
=======================================

Filenames within a pack can be of arbitrary length (subject to normal operating system/zip archive limitations), but must have a file extension
in order to prevent being potentially confused with a lump name during loading routines. A warning message will be produced in
the console and logfile if a filename without an extension is encountered, and it will not be added to the pack directory listing.

=======================================
Standard Folder and File References
=======================================

If using resources that are not referenced by any DDF entries, in order to have them be loaded and used like their equivalent
lumps, certain locations are enforced:

/colormaps - Location for raw COLORMAP files; no enforced file extension but usually .cmp or .lmp.
/flats, /graphics, /textures, and /sprites - Location for supported image files, extension must match file type 
                                             (.lmp is assumed to be a Doom format graphic).
/hires - Location for higher-resolution image files intended to inherit scaling and (in the case of sprites) offsets from the
         images they are replacing. This is analagous to the HI_START/HI_END WAD namespace that some ports support. If there is
         no image for which an item in this folder would be a replacement, it will be loaded as if it came from the /textures
         directory. Extension must match file type.
/skins - Location for MD2/MD3 model skin images with supported filetype; must be placed here instead of /sprites to avoid being treated
         as a sprite frame with rotation.
/sounds - Location for supported audio files intended to be used as sound effects. Extension must match file type
          (.lmp is assumed to be either a Doom or PC Speaker format sound).
/music - Location for supported audio files intended to be used as music tracks. Extension must match file type.

Subfolders within the aforementioned directories are acceptable, and need no specific naming convention or structure.

If a pack file is intended to replace a lump from a previous WAD in the load order, it must have an identical name (minus the file extension).
For instance, an entry of /music/D_RUNNIN.ogg would be used in lieu of the D_RUNNIN lump as far as the playlist is concerned.

Note that for images, the ^ character in a filename will be remapped to \ to support replacing sprite frames that use the problematic
(for file paths) \ character.

Palettes should be named "PLAYPAL.pal", and can reside anywhere in a pack although it is recommended to avoid placing it in the /colormaps folder to
avoid having it treated as a raw colormap file.

WADs within a pack will also be processed and do not need to reside in any particular location. That being said, any WAD within a pack
will be considered to come 'after' the pack itself for load order purposes. To avoid the confusion that this may cause, it is recommended to 
only store maps and their associated lumps within pack WADs. The alternative to this would be to store ALL in-game resources within a pack WAD, 
with documentation and other miscellany outside of it.

COAL, DDF, Lua and RTS scripts can be placed in any location within a pack, but the filenames must adhere to EDGE's historical standards. For ease
in converting mods that were previously in WAD form, filenames consisting of the lump name from the table below + any file extension will be
considered valid as well (i.e., COALHUDS.dat, DDFATK.txt, etc.):

Lump Name            Filename Equivalent
---------            -------------------

COALHUDS             coal_hud.ec
DDFANIM              anims.ddf
DDFATK               attacks.ddf
DDFCOLM              colmap.ddf
DDFFLAT              flats.ddf
DDFFONT              fonts.ddf
DDFGAME              games.ddf
DDFIMAGE             images.ddf
DDFLANG              language.ldf (Note, LDF not DDF!)
DDFLEVL              levels.ddf
DDFLINE              lines.ddf
DDFMOVIE             movies.ddf
DDFPLAY              playlist.ddf
DDFSECT              sectors.ddf
DDFSFX               sounds.ddf
DDFSTYLE             styles.ddf
DDFSWTH              switch.ddf
DDFTHING             things.ddf
DDFVERB              reverbs.ddf
DDFWEAP              weapons.ddf
LUAHUDS              edge_hud.lua
RSCRIPT              rscript.rts

=======================================
DDF Folder and File References
=======================================

When defining resource locations via DDF, there is no restriction or enforcement regarding where a file can be
located within a pack. 

If a complete path (folder + filename) is used, it should be relative to the root of the pack itself.

Full Path Example (a leading '/' is optional, and will produce the same result):

[SPR:SNW1A0]
IMAGE_DATA=PACK:"graphics/snowflakes/SNOW1.png";

or

[SPR:SNW1A0]
IMAGE_DATA=PACK:"/graphics/snowflakes/SNOW1.png";

This would be valid for a compressed archive that has an entry of /graphics/snowflakes/SNOW1.png, or a folder/file
path of C:\Users\EDGE-User\Pictures\graphics\snowflakes\SNOW1.png (assuming C:\Users\EDGE-User\Pictures was
mounted as a folder on startup)

If only a filename is provided, it will return the first matching file within a pack that it can find. The exception
to this is if the filename is immediately preceded by '/', in which case it will only search the root directory of the
pack in question for the filename.

Bare Filename Example:

[SPR:SNW1A0]
IMAGE_DATA=PACK:"SNOW1.png";

This will use the first SNOW1.png that it encounters unconditionally. The downside to this method is that if there are
multiple pack entries with the exact same filename, it is not guaranteed which one will be used. It is recommended
to either avoid identical file names, or to provide a full path if it is intended to use a specific entry.

Root Filename Example:

[SPR:SNW1A0]
IMAGE_DATA=PACK:"/SNOW1.png";

This will only use SNOW1.png if it is in the root of the pack, even if it is present elsewhere within it.